home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 20 / Cream of the Crop 20 (Terry Blount) (1996).iso / os2 / htmle96b.zip / HM-PROG.INF (.txt) < prev    next >
OS/2 Help File  |  1996-07-22  |  38KB  |  1,688 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. HTML-Ed REXX Functions ΓòÉΓòÉΓòÉ
  3.  
  4. The following functions are available for use in your REXX Macros: 
  5.  
  6.       hmChangeFilename 
  7.       hmCharFromLine 
  8.       hmCharsToTags 
  9.       hmClear 
  10.       hmCloseFile 
  11.       hmConvertSlashes 
  12.       hmCopy 
  13.       hmCurrentFile 
  14.       hmCut 
  15.       hmDelete 
  16.       hmDeselectAll 
  17.       hmDisableRefresh 
  18.       hmEnableRefresh 
  19.       hmExit 
  20.       hmFind 
  21.       hmGoToLine 
  22.       hmInsert 
  23.       hmInsertFile 
  24.       hmLineFromChar 
  25.       hmNew 
  26.       hmOpen 
  27.       hmOpenOutputWindow 
  28.       hmPaste 
  29.       hmQueryChanged 
  30.       hmQueryFilename 
  31.       hmQueryLineCount 
  32.       hmQueryLineLength 
  33.       hmQuerySel 
  34.       hmQuerySelText 
  35.       hmQueryTextLength 
  36.       hmQueryWrap 
  37.       hmRemoveTags 
  38.       hmResetUndo 
  39.       hmRingLeft 
  40.       hmRingFiles 
  41.       hmRingRight 
  42.       hmSaveAll 
  43.       hmSaveAs 
  44.       hmSaveASCII 
  45.       hmSaveCurrent 
  46.       hmSaveOptions 
  47.       hmSay 
  48.       hmSelectAll 
  49.       hmSetChanged 
  50.       hmSetSel 
  51.       hmSetWrap 
  52.       hmStatusSay 
  53.       hmSwitchTo 
  54.       hmTagsCase 
  55.       hmUndo 
  56.       hmVersion 
  57.       hmWrapAround 
  58.  
  59.  
  60. ΓòÉΓòÉΓòÉ <hidden> Introduction ΓòÉΓòÉΓòÉ
  61.  
  62. Welcome to the HTML-Ed Programmer's Reference! 
  63.  
  64. HTML-Ed extends the REXX language with 52 new functions.  These functions are 
  65. explained in this reference manual. 
  66.  
  67. If this is the first time you have used the .HM Macro functions, please read 
  68. over this entire document before proceeding.  Many of the functions have 
  69. important remarks that you should be aware of before using them. 
  70.  
  71. Things to remember: 
  72.  
  73.      Name your HTML-Ed macros with an .HM extension.  This is not strictly 
  74.       necessary, but it will help you to tell apart normal REXX .CMD files and 
  75.       REXX macros that use the HTML-Ed extended functions. 
  76.  
  77.      The .HM macro functions are very powerful - but power comes at a price. 
  78.       The functions are not crash proof and you can crash HTML-Ed if you are 
  79.       not careful.  Always check the return codes a function returns (unless 
  80.       there is only one possible return code) and take appropriate action.  For 
  81.       functions that require parameters, make sure you are passing it a correct 
  82.       value. 
  83.  
  84.      Take special care that you do not enter an infinite loop.  HTML-Ed will 
  85.       not be able to recover from a stuck macro. 
  86.  
  87.      Your macro runs on HTML-Ed's main thread!  (This will change in the 
  88.       future).  Therefore, while your macro is running you will not be able to 
  89.       interact with any windows (the message queue will be "hung").  If your 
  90.       macro is taking a long time to complete, or if it gets stuck in an 
  91.       infinite loop, pressing Ctrl+ESC a few times should bring up a dialog 
  92.       that will allow you to kill HTML-Ed (alternatively, you could use a 
  93.       process killer such as Watchcat to kill HTML-Ed).  It is a good idea to 
  94.       make sure your macros are short. 
  95.  
  96.      An insertion point is just a number.  "0" is the insertion point before 
  97.       the first character in the editor.  Take special care to ensure that any 
  98.       insertion points you are using are valid - any time you insert or remove 
  99.       any text the insertion points after the changed portion will be invalid. 
  100.       Take extreme care when writing looping search/replace macros as it is 
  101.       very easy to become stuck in an infinite loop. 
  102.  
  103.      Use hmSay instead of Say.  If more than 32kb of text is written to stdout 
  104.       HTML-Ed will appear to crash (in reality, HTML-Ed is waiting for the 
  105.       macro to finish and the macro is waiting for the unnamed pipe to be 
  106.       cleared - so nothing happens).  This will be addressed in a future 
  107.       version. 
  108.  
  109.  If you have problems: 
  110.  
  111.       Nothing appears to be happening! 
  112.  
  113.                          .HM macros simply stop execution when there is an 
  114.                           error.  When an error occurs, anything written to 
  115.                           stdout does not get copied to the output window (use 
  116.                           hmSay to overcome this problem).  If you have a 
  117.                           syntax error in your program and you have been using 
  118.                           say instead of hmSay it may appear as if nothing has 
  119.                           happened. 
  120.  
  121.                          You can use hmSay to help track down the problem. 
  122.  
  123.       One of the functions doesn't work as it should! 
  124.  
  125.                          First, make sure you read (and re-read) all the 
  126.                           appropriate information in this manual.  If the 
  127.                           problem persists, contact me. 
  128.  
  129.  Contacting the author: 
  130.  
  131.      HTML-Ed's author, Ian Prest, may be contacted in the following ways: 
  132.  
  133.       email:         ianprest@connect.reach.net (put "HTML-Ed" somewhere on the 
  134.                      subject line) 
  135.  
  136.       snail mail: 
  137.  
  138.                                           Ian Prest
  139.                                           R.R.#1
  140.                                           Shannonville, Ontario
  141.                                           K0K 3A0
  142.                                           re: HTML-Ed
  143.  
  144.      Visit the HTML-Ed Home Page on the internet! 
  145.       http://www.wp.com/ianprest/htmled.html 
  146.  
  147.  
  148. ΓòÉΓòÉΓòÉ 1.1. hmChangeFilename ΓòÉΓòÉΓòÉ
  149.  
  150.  Function:  hmChangeFilename 
  151.  
  152.  Purpose:   to change the filename of the current editor 
  153.  
  154.  Syntax:    rc = hmChangeFilename(file) 
  155.  
  156.            file           the new filename 
  157.  
  158.  Returns:  0 
  159.  
  160.  Remarks: 
  161.  
  162.            hmChangeFilename changes the name of the current file, but does not 
  163.            save anything with the new filename, and does not alter the file's 
  164.            "changed" flag. 
  165.  
  166.            hmChangeFilename is usually used after a call to hmSaveAs. 
  167.  
  168.  Example: 
  169.  
  170.  
  171.                       /* Save the file with a new filename */
  172.                       call hmSaveAs "newfile.htm"
  173.  
  174.                       /* Update the titlebar's filename to reflect the change */
  175.                       call hmChangeFilename "newfile.htm"
  176.  
  177.  
  178. ΓòÉΓòÉΓòÉ 1.2. hmCharFromLine ΓòÉΓòÉΓòÉ
  179.  
  180.  Function:  hmCharFromLine 
  181.  
  182.  Purpose:   to find the insertion point of the first character of a line 
  183.  
  184.  Syntax:    ipt = hmCharFromLine(line) 
  185.  
  186.            line           line number of interest 
  187.  
  188.  Returns:  insertion point of the first character of line 'line' 
  189.  
  190.  Remarks: 
  191.  
  192.            Use hmCharFromLine to determine where a line starts. 
  193.  
  194.  Example: 
  195.  
  196.  
  197.                       /* example to "home" the cursor */
  198.  
  199.                       /* get cursor position */
  200.                       ipt = hmQuerySel("cursor")
  201.  
  202.                       /* get current line */
  203.                       line = hmLineFromChar(ipt)
  204.  
  205.                       /* find start of current line */
  206.                       ipt = hmCharFromLine(line)
  207.  
  208.                       /* set cursor position */
  209.                       call hmSetSel ipt,ipt
  210.  
  211.  
  212. ΓòÉΓòÉΓòÉ 1.3. hmCharsToTags ΓòÉΓòÉΓòÉ
  213.  
  214.  Function:  hmCharsToTags 
  215.  
  216.  Purpose:   to convert characters to HTML character identities 
  217.  
  218.  Syntax:    rc = hmCharsToTags() 
  219.  
  220.  Returns: 
  221.  
  222.            0              No error 
  223.            1              No text was selected 
  224.  
  225.  Remarks: 
  226.  
  227.            hmCharsToTags works exactly as the "Convert characters to tags" menu 
  228.            function does, converting all the characters in the selected text to 
  229.            their HTML equivilants. 
  230.  
  231.  Example: 
  232.  
  233.  
  234.                       /* Convert all special characters to tags */
  235.                       call hmCharsToTags
  236.  
  237.  
  238. ΓòÉΓòÉΓòÉ 1.4. hmClear ΓòÉΓòÉΓòÉ
  239.  
  240.  Function:  hmClear 
  241.  
  242.  Purpose:   to delete the current selection 
  243.  
  244.  Syntax:    rc = hmClear() 
  245.  
  246.  Returns:  0 
  247.  
  248.  Remarks: 
  249.  
  250.  Example: 
  251.  
  252.  
  253.                       /* delete the current selection */
  254.                       call hmClear
  255.  
  256.  
  257. ΓòÉΓòÉΓòÉ 1.5. hmCloseFile ΓòÉΓòÉΓòÉ
  258.  
  259.  Function:  hmCloseFile 
  260.  
  261.  Purpose:   to close the current file 
  262.  
  263.  Syntax:    rc = hmCloseFile() 
  264.  
  265.  Returns: 
  266.  
  267.            0              No error 
  268.            1              Last file closed - HTML-Ed will now